home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / utility / fdate.zip / FDATEBEG.TXT < prev    next >
Text File  |  1997-05-22  |  10KB  |  238 lines
  1. FDATEBEG.DOC    --   A "quick start" introduction to using Fdate
  2. ======================================================================
  3. Revision date: 1996 Feb 1
  4.  
  5. "Everything you'd ever want to do with dates in batch files"
  6.  
  7. INTRODUCTION: WHAT IS FDATE?
  8. ============================
  9. Fdate is a utility for doing date formatting and date arithmetic in DOS
  10. batch files.  There are a number of different ways to put FDATE's output
  11. into environment variables.  Once this has been done, the environment
  12. variables can be used and manipulated in many ways in the batch file.
  13.  
  14. FDATE is freeware, or what is technically known as "zero-cost shareware". 
  15. There is no requirement to register FDATE in any way.  For more details,
  16. see the DISTRIBUTION ISSUES section in the FDATE.DOC file.
  17.  
  18. Here are some of the things you can do with FDATE.
  19.  
  20.     accept user input from the keyboard
  21.  
  22.     retrieve today's date in a variety of formats
  23.       place today's date into a file name
  24.  
  25.     reformat dates 
  26.        Output formats include common American and European formats, or you
  27.        can "roll your own" by manipulating environment variables.  Month
  28.        and weekday names can be produced in several languages (English,
  29.        French, German, Spanish).
  30.  
  31.     calculate the dates of holidays in a given year
  32.  
  33.     do date arithmetic
  34.       determine the date N days before/after a given date
  35.       compare two dates to determine which is earlier
  36.       compare two dates to determine how many days apart they are
  37.  
  38.     determine if a year is a leap year
  39.     determine whether a year is evenly divisible by some number
  40.  
  41.     determine what day of the week a date falls on
  42.       run certain software only on certain days of the week
  43.  
  44.     retrieve the date/time from the date/timestamp of a file
  45.     do simple integer arithmetic (add, subtract, modulus)
  46.     calculate the time a piece of software takes to run
  47.     convert a calendar date to/from a "business julian" date
  48.  
  49.     extract a substring from an environment variable
  50.     right, left, or center justify a string
  51.  
  52. Fdate's original purpose was to do date formatting and date arithmetic in
  53. DOS batch files.  Over the years, functions were added to Fdate to support
  54. activities that people often need to do in conjunction with working with
  55. dates (simple arithmetic and string manipulation, for instance).  As Fdate
  56. grew, the documentation grew also.  Fdate's documentation file, FDATE.DOC,
  57. is now quite large and rather intimidating.  Some new users have reported
  58. having a hard time using FDATE.DOC to learn how to use FDATE do the basic
  59. tasks that they need to do with dates. 
  60.  
  61. To help you get started using Fdate, I've created this short file called
  62. FDATEBEG.DOC (FDATE beginners documentation), which shows how to use Fdate
  63. to do the things most users want to do.  If you're using Fdate for the
  64. first time, I suggest that you start by reading this.  
  65.  
  66. When you've finished, you may still have a question: "Can I do such-and-
  67. such with Fdate?"  If it involves dates, it can probably be done with
  68. Fdate, although tricky things are of course tricky to do, even with Fdate.  
  69. A good next step would be to look at the list of examples in FDATE.DOC. 
  70. With luck, you will find Fdate doing such-and-such in one of the examples. 
  71. To understand how Fdate is working in a particular example, use the
  72. "language reference manual" part of the FDATE.DOC to look up the parameters
  73. used in the example.
  74.  
  75. When all else fails, reading the documentation often proves useful.
  76.  
  77.    Good Luck! 
  78.    Steve Ferg
  79.  
  80. THE 3-MINUTE INTRODUCTION TO FDATE
  81. ==================================
  82.  
  83. By far the most popular use of Fdate is to put today's date-- in a
  84. particular format-- into an environment variable.  Once this has been done,
  85. the environment variable can be used and manipulated in many ways in a
  86. batch file.  Here are a few short exercises that will help you to learn how
  87. to use Fdate's most basic features to do that.
  88.  
  89.  
  90. 1.
  91. At the DOS prompt, type:  
  92.   
  93.        FDATE
  94.  
  95.   This will show you Fdate's HELP screens.  Press ENTER to page through
  96.   the HELP screens.
  97.  
  98.   The information on these HELP screens is very dense.  It won't teach you
  99.   how to use Fdate, but it is useful for jogging your memory as you become
  100.   familiar with Fdate's various features.
  101.  
  102. 2.
  103. At the DOS prompt, type:  
  104.  
  105.        FDATE /Ff
  106.  
  107.   I've used lowercase "f" here to distinguish the value of the parameter
  108.   from the parameter-letter itself, but it really doesn't matter whether
  109.   the parameter or its value is in upper or lower case.  Except for the /K
  110.   parameter (one of Fdate's advanced features), Fdate's parameters are not
  111.   case sensitive.
  112.  
  113.   Here, the value of the "/F" (function) parameter is "f" (format a date). 
  114.   The "/Ff" parameter tells Fdate that the function you want it to perform
  115.   is to format a date.  Since the default date is "today", this command
  116.   will cause Fdate to display today's date on your screen in Fdate's
  117.   default output format.
  118.  
  119. 3.
  120. At the DOS prompt, type:
  121.  
  122.        FDATE /Ff /P"Today is "
  123.  
  124.   This command is just like the one in the previous example, except that
  125.   we've specified the "prefix parameter" (/P), which tells Fdate to add a
  126.   string to the beginning of its output.  (There is also a "suffix
  127.   parameter" that tells Fdate to add a string to the end of its output.) 
  128.   Note that the value of the /P parameter is enclosed in quotes.  (Either
  129.   single quotes or double quotes will work.)  We've had to enclose the
  130.   value in quotes because it contains embedded blanks (one blank after the
  131.   word "today" and another after the word "is"). 
  132.  
  133. 4.
  134. At the DOS prompt, type: 
  135.  
  136.        FDATE /Ff /Occyymmdd
  137.  
  138.   (Or you can put the same statement in a batch file.)
  139.  
  140.   Here, you are telling Fdate to put out today's date in a specific
  141.   format.  On the "output format" parm (/O) you are specifying that you
  142.   want the day in "ccyymmdd" format: two digits each for century, year-
  143.   within-century, month, day-of-month.
  144.  
  145.   Note that the /O parm is not free-format.  Fdate supports many (but a
  146.   finite number) of output formats.  If you request output in (for
  147.   example) "yyccddmm" format, Fdate will reject your request, because it
  148.   does not support that particular output format.  Then you will have to
  149.   "roll your own" date format (see below).
  150.  
  151. 5.
  152. At the DOS prompt, type:
  153.  
  154.        FDATE /Ff /Omm/dd/ccyy 
  155.  
  156.   Here, you are telling Fdate to put out today's date in another of its
  157.   supported output formats, in this case "mm/dd/ccyy".
  158.  
  159.  
  160. 6.
  161. At the DOS prompt, type:
  162.  
  163.        FDATE /Ff /Occyymmdd /Vdate1
  164.  
  165.   (Or you can put the same statement in a batch file.)
  166.  
  167.   Here, you are telling Fdate to put out today's date in "ccyymmdd"
  168.   format.  Because you are specifying the "environment variable" parm (/V)
  169.   as "date1", Fdate is not writing its output to the screen.  It is
  170.   putting its output in an environment variable called "date1".  Now, if
  171.   you type "SET" at the DOS prompt, and if today is February 1, 1995, you
  172.   will see as the last line of the SET output:
  173.  
  174.             DATE1=19950201
  175.  
  176.   At this point, you know everything you need to know to put today's date
  177.   into an environment variable, which you can then use for whatever you
  178.   want.  Here's an example in which you are copying a file (BACKUP.LOG,
  179.   which is put out by a backup program) to a file whose name contains
  180.   today's date.
  181.  
  182.             FDATE /Ff /Occyymmdd /Vdate1
  183.             copy BACKUP.LOG  %date1%.LOG
  184.  
  185. 7.
  186.   Everybody, it seems, has their own preferred, and often unique, date
  187.   format.  Most likely, you will want the date in some format other than
  188.   "ccyymmdd". 
  189.  
  190.   To see if Fdate supports the output format that you want, look at the
  191.   FDATE help screens (as you did in step 1, above), or look at the
  192.   complete documentation in FDATE.DOC.
  193.  
  194.   If you find that Fdate does not support the precise date format that you
  195.   want, you can "roll your own" by putting one component of the date into
  196.   an environment variable, and then using the /P (prefix) facility to
  197.   concatenate it onto the front of another component of the date.  Using
  198.   this technique, you can build up virtually any date format you might
  199.   want.  Here is an example.  You can copy it into a batch file and see
  200.   that it actually does what it is supposed to do.
  201.  
  202.      @echo off
  203.      :: create a date in custom format: yy-mn3-dd
  204.      :: note the use of temporary work variable: r
  205.      Fdate /Ff /Oyy           /Vr
  206.      Fdate /Ff /Omn3 /P"%r%-" /Vr
  207.      Fdate /Ff /Odd  /P"%r%-" /Vr
  208.      echo Today is %r%
  209.  
  210.  
  211. WHAT TO DO NEXT?
  212. ================
  213. Now that you know the basics, you may have everything you need to know in
  214. order to use FDATE to satisfy your basic date-handling needs.  If you need
  215. more information, or are feeling adventurous, your next step should be to
  216. explore the FDATE.DOC file.  It documents many more features of FDATE.  
  217.  
  218. One of the most useful parts of FDATE.DOC is the list of examples.  Browse
  219. through the titles of the examples in the Table of Contents of FDATE.DOC,
  220. getting a feel for what is there.  Then look at the examples themselves. 
  221. Many are quite elaborate (which is natural, since they are there to show
  222. you how to do Hard Stuff).  If example :47 looks interesting, use your
  223. browser/viewer/editor find/search command to look for the string ":47" --
  224. that should take you right to the example you're interested in.
  225.  
  226. Most of the examples are self-contained and ready-to-run -- if you copy the
  227. text of the example into a batch file, the example code will run and do
  228. what the title says it will do.  I suggest you try doing so with one or two
  229. of the examples that seem most interesting to you.
  230.  
  231. After the examples, the most useful parts of FDATE.DOC are the sections
  232. documenting Fdate's various functions (the functions that you can specify
  233. on the function parm, /F) and its various output formats.  I suggest you
  234. scan those sections, just to get a quick feel for what's available to you.
  235.  
  236.    Good Luck! 
  237.    Steve Ferg
  238.